home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1995 #1 / Amiga Plus 1995 #1.iso / fish-disketten / fish_811-820 / d818 / watchstack / watchstack.doc < prev    next >
Text File  |  1994-12-13  |  9KB  |  482 lines
  1.  
  2.      v2.01                   WatchStack Manual                        1
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.  
  13.  
  14.  
  15.  
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.  
  23.                                  WatchStack
  24.                           A Postcard-Ware Utility
  25.                           written by Brian Ipsen,
  26.                   © copyright 1993 by GizmoSoft Productions,
  27.                             All rights reserved.
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.      v2.01                 GizmoSoft Productions                      1
  61.  
  62.      v2.01                   WatchStack Manual                        2
  63.  
  64.  
  65.      1. Disclaimer 
  66.      ------------- 
  67.  
  68.       No guarantee  of  any kind is given that the program described in
  69.      this  document  is  100%  reliable. You are using this material on
  70.      your own risk.   
  71.       The author  does  not  take any responsibility for the results of
  72.      the  use  or  misuse  of this software.  The entire risk as to the
  73.      results  and  performance of this software is assumed by the user.
  74.      The  author  is  not  responsible for any damage including loss of
  75.      any   data   or   information   which  may  be  lost  or  rendered
  76.      inaccurate.   
  77.       WatchStack is  a  Postcard-Ware  program  (concept  introduced by
  78.      Klaus  Seistrup,  DK).  If  you  like  this  program  and  use  it
  79.      regulary,  you  are  obliged to send a postcard to the author. The
  80.      address is at the bottom of this text-file.  
  81.  
  82.  
  83.  
  84.  
  85.  
  86.  
  87.  
  88.  
  89.  
  90.  
  91.  
  92.  
  93.  
  94.  
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.      v2.01                 GizmoSoft Productions                      2
  121.  
  122.      v2.01                   WatchStack Manual                        3
  123.  
  124.  
  125.      2. Introduction 
  126.      --------------- 
  127.  
  128.       This program  was  written, because StackWatch by James R. Locker
  129.      had some 'minor' bugs, which I didn't like.  
  130.  
  131.      1: It (sort of) expected that the task to be watched already 
  132.         was running.  
  133.      2: When the task finished, it was impossible to see how much 
  134.         stack the specified program/task used, because the window 
  135.         was overwritten.  
  136.  
  137.        What WatchStack  does  is  really  quite  simple. It watches the
  138.      stack  of  a  task  or process that you select. It will be updated
  139.      every  time  the  vblank-interrupt  is  activated. The text in the
  140.      window  will  only  be  updated for every 3rd interrupt, but still
  141.      fast enough to catch the needed values.  
  142.  
  143.       If you  set  your stack up to a huge number, you will probably be
  144.      safe,  but  you  are also wasting a lot of memory. What is needed,
  145.      is  a good way to tell, dynamically, how any program is doing. You
  146.      may then tailor your stack allocations to be more efficient.  
  147.  
  148.      WatchStack helps you with this by watching the stack-usage.  
  149.  
  150.  
  151.  
  152.  
  153.  
  154.  
  155.  
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.      v2.01                 GizmoSoft Productions                      3
  181.  
  182.      v2.01                   WatchStack Manual                        4
  183.  
  184.  
  185.      3. Using WatchStack 
  186.      ------------------- 
  187.  
  188.       WatchStack requires  at  leat AmigaDOS Release 2.0 to run. If you
  189.      don't   have  the  2.0-Kickstart,  forget  all  about  using  this
  190.      program.  
  191.       WatchStack starts  from  CLI  only.  It requires one command line
  192.      argument,  which  is  the  name  of  the  task  or  process  to be
  193.      monitored.  This  name must be entered EXACTLY as it is maintained
  194.      in  the  system  task lists.  WatchStack is not case sensitive, so
  195.      if  you  use  an upper case letter while the system knows the task
  196.      by a lower case letter, it will still work.  
  197.  
  198.      The syntax is as follows: 
  199.  
  200.      1> Run WatchStack MyTaskName  <RETURN> 
  201.  
  202.      For instance,  
  203.  
  204.      1> Run WatchStack Scribble! 
  205.  
  206.       will monitor Scribble!.  
  207.  
  208.      WatchStack   will   find   Workbench   or   CLI  applications.  An
  209.      application  started from Workbench will have the exact name shown
  210.      on  the  icon.   An application started from CLI may be known by a
  211.      number  of  different  names,  depending  upon how it hooks itself
  212.      into  the  system.   For  instance,  if  you  start the Calculator
  213.      utility  that  is  found  in the Utilities drawer of the Workbench
  214.      disk   by   clicking    on   its  icon,  it  will  have  the  name
  215.      "Calculator" and typing: 
  216.  
  217.      1> Run WatchStack Calculator 
  218.  
  219.       will now find the task/process in the task-list.  
  220.  
  221.       To exit   the   program,  simply  close  the  WatchStack  window.
  222.      WatchStack  will  then  write  3  lines in the CLI, it was started
  223.      from.  These  3 lines shows the taskname, allocated stack and max.
  224.      usage. Usefull, if you need them in a text-file.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.      v2.01                 GizmoSoft Productions                      4
  241.  
  242.      v2.01                   WatchStack Manual                        5
  243.  
  244.  
  245.      4. The WatchStack Window 
  246.      ------------------------ 
  247.  
  248.       The WatchStack-window  has  four  lines. The first line tells you
  249.      what  process  (or  task) WatchStack is monitoring. This is useful
  250.      if  you are running multiple copies of WatchStack. The second line
  251.      tells  you  what  the  stack  allocation  for that process is. The
  252.      third  line tells you what the largest amount of stack used was at
  253.      any  time  since WatchStack was invoked. The fourth line tells you
  254.      what the stack usage is right now.  
  255.  
  256.  
  257.      5. WatchStack limitations 
  258.      ------------------------- 
  259.  
  260.       WatchStack takes  "snapshots" of your process - it is not looking
  261.      continuously.  Therefore,  it  won't necessarily spot a quick peak
  262.      in stack usage.  
  263.  
  264.       WatchStack hooks  itself  into  the  system  at  priority 10, and
  265.      wants  to run at frequent intervals.  One of the  first  things it
  266.      does  when  running  is  disable  multitasking  so it  can  safely
  267.      wander   through   the  system  Task  lists.   As  a  consequence,
  268.      under    certain    circumstances,    or  if  multiple  copies  of
  269.      WatchStack are running, it can noticeably slow system response.  
  270.  
  271.       If multiple  tasks  of  the same name are running on your system,
  272.      the  first  task found in the task-list will be used. I don't know
  273.      yet  how  to  handle  this situation, but it might be handled in a
  274.      future revision of the program.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.      v2.01                 GizmoSoft Productions                      5
  301.  
  302.      v2.01                   WatchStack Manual                        6
  303.  
  304.  
  305.      6. Acknowledgements and Thank You's  
  306.      -----------------------------------  
  307.  
  308.       The following  names  are either trademarks or the efforts of the
  309.      person and/or company listed:  
  310.       - Amiga, AmigaDOS, CLI, WorkBench and Kickstart by 
  311.         Commodore-Amiga, Inc.  
  312.       - StackWatch by James R. Locker 
  313.       - Postcard-Ware by Klaus Seistrup 
  314.  
  315.      Thank-you's:  
  316.      ------------  
  317.  
  318.       Thanks goes  to  these  two  persons,  who  helped  me build this
  319.      program.   I  don't  think  I  could  have  made  it without their
  320.      assistance.  
  321.  
  322.         2:230/119, Klaus Seistrup, for the Process-find sourcecode 
  323.         2:230/413, Jesper Kehlet, for help with finding the stack 
  324.                    information.  
  325.  
  326.       And greetings to these beta-testers of this program: 
  327.  
  328.         2:230/119, Klaus Seistrup 
  329.         2:230/413, Jesper Kehlet 
  330.         2:231/84,  Per Hansen 
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.  
  360.      v2.01                 GizmoSoft Productions                      6
  361.  
  362.      v2.01                   WatchStack Manual                        7
  363.  
  364.  
  365.      7. Author's notes on distribution  
  366.      ---------------------------------  
  367.  
  368.       WatchStack may  only  be  re-distributed  in  it's original form.
  369.      This program may be included in PD-series and uploaded on BBS'.  
  370.  
  371.  
  372.      8. Words from the author  
  373.      ------------------------ 
  374.  
  375.       The author  (Brian  Ipsen) may be reached in any of the following
  376.      ways:  
  377.  
  378.      Postal service:  
  379.  
  380.       GizmoSoft Productions  
  381.       c/o B. Ipsen  
  382.       Lyngens Kvarter 117, st.tv.   
  383.       DK-7400 Herning  
  384.       Denmark  
  385.  
  386.      BBS:  
  387.       For a  while  at  least,  I will be picking up mail on MicroAmiga
  388.      BBS  in  Randers/DK,  (2:230/813@fidonet  & 2:230/814@fidonet), an
  389.      official  StarNet/MEBBSNet  Support  Board  in  Europe.  (I'm also
  390.      working as CoSysop there).   
  391.       If you   haven't   logged   in there yet, you should. The numbers
  392.      are +45 86437939 and +45 86401535.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.  
  405.  
  406.  
  407.  
  408.  
  409.  
  410.  
  411.  
  412.  
  413.  
  414.  
  415.  
  416.  
  417.  
  418.  
  419.  
  420.      v2.01                 GizmoSoft Productions                      7
  421.  
  422.  
  423.  
  424.  
  425.                              Table of Contents
  426.  
  427.  
  428.      1. Disclaimer...............................................    2
  429.  
  430.      2. Introduction.............................................    3
  431.  
  432.      3. Using WatchStack.........................................    4
  433.  
  434.      4. The WatchStack Window....................................    5
  435.  
  436.      5. WatchStack limitations...................................    5
  437.  
  438.      6. Acknowledgements and Thank You's ........................    6
  439.  
  440.      7. Author's notes on distribution ..........................    7
  441.  
  442.      8. Words from the author ...................................    7
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.  
  471.  
  472.  
  473.  
  474.  
  475.  
  476.  
  477.  
  478.  
  479.  
  480.  
  481.  
  482.